home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / crossref.arc / CROSSREF.DOC < prev    next >
Text File  |  1984-06-16  |  23KB  |  722 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                               Computerenergy's CROSSREF
  9.  
  10.                                Cross Reference Utility
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.                                     Version 1.02
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.                                  Proprietary Notice
  45.  
  46.      CROSSREF is a proprietary product developed by Richard C.  Bemis and
  47.      distributed by Computerenergy Corporation, Denver, Colorado.  
  48.  
  49.      Copyright 1982 by Richard C.  Bemis and Computerenergy Corporation.  All
  50.      rights reserved except those expressly granted to the user within this
  51.      document.  
  52.  
  53.      Computerenergy Corporation, PO Box 6267, Denver, CO 80206 (303) 233-9118
  54.      Source: ST6070 
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.                                         - i -
  62.                                   TABLE OF CONTENTS
  63.  
  64.      Section                                                              Page
  65.  
  66.  
  67.  
  68.      CHAPTER 1  CROSSREF DISTRIBUTION NOTICE .............................   1
  69.  
  70.      CHAPTER 2  INTRODUCTION .............................................   2
  71.  
  72.      CHAPTER 3  SYSTEM SETUP .............................................   3
  73.         3.1  Copying CROSSREF ............................................   3
  74.         3.2  Program Setup - Final Installation ..........................   3
  75.  
  76.      CHAPTER 4  OPERATION ................................................   4
  77.         4.1  Execution ...................................................   4
  78.         4.2  Entering Responses ..........................................   4
  79.         4.3  Maillist/Donation Assistance ................................   4
  80.         4.4  Program Entry ...............................................   4
  81.         4.5  Statistics and Limitations ..................................   5
  82.            4.5.1  Limitations ............................................   5
  83.         4.6  Programming Tip .............................................   6
  84.  
  85.      CHAPTER 5  OPTION DEFAULTS ..........................................   7
  86.         5.1  Program Name Extension ......................................   7
  87.         5.2  Beginning Program Line Number ...............................   7
  88.         5.3  Ending Program Line Number ..................................   7
  89.         5.4  Changing Default Options ....................................   7
  90.  
  91.      CHAPTER 6  OTHER INFORMATION ........................................   9
  92.         6.1  Distribution Disk Contents ..................................   9
  93.         6.2  System Requirements .........................................   9
  94.         6.3  Disclaimer ..................................................   9
  95.  
  96.      CHAPTER 7  SUGGESTIONS, FEEDBACK, AND BUG REPORTS ...................  10
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.      CROSSREF                          - ii -       Computerenergy Corporation
  122.                                       CHAPTER 1
  123.  
  124.                             CROSSREF DISTRIBUTION NOTICE
  125.  
  126.      CROSSREF is  being distributed  using the "Freeware"* approach.  To those
  127.      of you unfamiliar  with this approach, it works  like this.  You may send
  128.      either a  preformatted single-sided  disk (or a prepaid contribution  for
  129.      our disk  and mailer) to us with a prepaid return mailer and we will send
  130.      a complete copy of the product.  If the product does not meet your needs,
  131.      please pay nothing.  If the product does meet your needs, and you can use
  132.      it,  then  we  would appreciate  a contribution  of  whatever you feel is
  133.      appropriate.   Naturally, we  have probably  given you a clue in  several
  134.      places  as  to  what  is  our  "completely  unprejudiced  opinion" of  an
  135.      appropriate contribution  amount.  Contributions are completely voluntary
  136.      and much encouraged.  
  137.  
  138.      Even if you  do not contribute, you are encouraged to copy and distribute
  139.      the product freely subject to the following restrictions: 
  140.  
  141.           1. Do  not distribute  altered copies.   Note:  You may distribute a
  142.              separate set  of modifications  to merge in if you  wish but they
  143.              must   be    clearly   identified   as   not   originating   from
  144.              Computerenergy.  If you  do make modifications, we would  like to
  145.              see what you've done, if possible, for future versions.  
  146.  
  147.           2. The  product  is to  be distributed  as  a complete "distribution
  148.              copy" produced  by the copy utility provided with the product for
  149.              this purpose.  
  150.  
  151.           3. No fee is  to be charged for copying  or distributing the program
  152.              without   an   express  written   agreement  with  Computerenergy
  153.              Corporation.  
  154.  
  155.           4. Commercial  sale  of  this product  in any  manner  is prohibited
  156.              without Computerenergy's  written permission.  Some products will
  157.              be   released  with   this  permission  automatically  given  and
  158.              expressly stated.  
  159.  
  160.      User Groups/Clubs: Computerenergy's  freeware products may be distributed
  161.      by Clubs  and User Groups subject to the same restrictions.  We would ask
  162.      only that  contributions to our continuing efforts be encouraged by those
  163.      performing such distribution.  
  164.  
  165.      Computer Bulletin  Boards:  Computerenergy's  freeware  products  may  be
  166.      distributed by  BBS's subject  to the same restrictions and  contribution
  167.      encouragement.  However,  as the products tend to be large and consist of
  168.      several  files,   we  have   some  concern  as  to  the   reliability  of
  169.      transmissions and  length of connect time.  Perhaps disks could be mailed
  170.      or just the documentation placed on the board for browsers.  
  171.  
  172.  
  173.      * The Freeware concept  was initially developed by Andrew  Fluegelman and
  174.      the  term  "FREEWARE" is  a trademark  of The Headlands Press, Inc.   The
  175.      Headlands Press provides a catalog of information about Freeware products
  176.      available from  multiple sources.   They may be contacted at  PO Box 862,
  177.      Tiburon, CA 94920 or Source: TCP204 or Compuserve: 71435,1235.  
  178.  
  179.  
  180.  
  181.      CROSSREF                          - 1 -        Computerenergy Corporation
  182.                                       CHAPTER 2
  183.  
  184.                                     INTRODUCTION
  185.  
  186.  
  187.      Computerenergy's Cross  Reference  was  created  to make  programming and
  188.      maintenance jobs  easier.  We feel that a computer should help as much as
  189.      possible  in its  own  development  efforts.   CROSSREF  is a  tool  that
  190.      produces  a cross-reference  for each  reference to a variable or  a line
  191.      number  within a  program.  Multiple  occurances of a variable or  a line
  192.      number on a single line will be referenced for each occurance.  
  193.  
  194.  
  195.  
  196.      After you have  setup  the  system  and  read the  Operation  chapter, we
  197.      recommend that you try CROSSREF on some of your own programs.  If you are
  198.      going to "wing-it"  without reading further, then SAVE  the Basic program
  199.      to  be  cross-referenced in  ASCII (true  wingers  understand this), type
  200.      CROSSREF, and good luck!  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.      CROSSREF                          - 2 -        Computerenergy Corporation
  242.                                       CHAPTER 3
  243.  
  244.                                     SYSTEM SETUP
  245.  
  246.  
  247.      The Cross Reference distribution  disk contains a version of  the program
  248.      in compiled format along with its Syntax file and Options file.  Compiled
  249.      versions are being distributed as they execute much faster.  
  250.  
  251.      3.1  Copying CROSSREF
  252.  
  253.           There is a  batch file which copies the entire distribution disk for
  254.           backup  or  distribution  purposes.   We  highly recommend  making a
  255.           backup copy  before proceeding  as it is safer and  the mails can be
  256.           slow.  
  257.  
  258.           Place the Cross  Reference  distribution  disk  in  Drive A:  and  a
  259.           formatted disk  without DOS  on it in Drive B:.   While in DOS, type
  260.           CRCOPY and follow any instructions.  
  261.  
  262.      3.2  Program Setup - Final Installation
  263.  
  264.           We recommend that  a copy of CROSSREF, its control file CROSSWDS.DAT
  265.           and  its  options file  CROSSOPT, all  be placed on a Basic  Program
  266.           Development  DOS  System disk  if possible.   If  this is your first
  267.           run-through,  do not  perform this  step yet - use your  copy of the
  268.           distribution disk and proceed to the Operation Chapter.  
  269.  
  270.           1. Copy CROSSREF.EXE to the System disk.  
  271.  
  272.                   A Sample COPY command might be:
  273.  
  274.                                  COPY B:CROSSREF.EXE A:
  275.  
  276.           2. Copy the CROSSWDS.DAT  file to the same disk.   This file must be
  277.           available any time CROSSREF is used.  
  278.  
  279.                   A sample COPY command might be:
  280.  
  281.                                  COPY B:CROSSWDS.DAT A:
  282.  
  283.           3. Copy the  CROSSOPT file to the same disk.  This file must also be
  284.           available any time CROSSREF is used.  
  285.  
  286.                   A sample COPY command might be:
  287.  
  288.                                  COPY B:CROSSOPT A:
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.      CROSSREF                          - 3 -        Computerenergy Corporation
  302.                                       CHAPTER 4
  303.  
  304.                                       OPERATION
  305.  
  306.      4.1  Execution
  307.  
  308.           Starting Cross  Reference  is simply  a matter  of  entering DOS and
  309.           typing CROSSREF followed by the Enter key.  
  310.  
  311.      4.2  Entering Responses
  312.  
  313.           You will quickly  notice that all input requested by Cross Reference
  314.           is at  the bottom  of the screen, following a  prompt, and contained
  315.           within a  "target".  We  have found that a relatively  constant area
  316.           for  data  entry   is  superior  to  the  more   typical  design  of
  317.           "fill-in-the-blanks"  as  it minimizes  eye travel and usually makes
  318.           for a more consistant entry process.  All responses are completed by
  319.           pressing the  Enter key.   In several prompts, and on  the keyboard,
  320.           the Enter  key is  represented by a symbol roughly  similar to this:
  321.           (<-').  
  322.  
  323.           In addition to the normal editing functions provided for inner-field
  324.           editing there are a couple of special functions available: 
  325.  
  326.                Field Erase:  Press the ESC key to erase an entry and start
  327.                              over or to change a field that has a pre-loaded
  328.                              value.
  329.  
  330.                Field Backup: Press the Up-Arrow to "backup" to the previous
  331.                              entry.  The current entry will be erased as you
  332.                              "backup".
  333.                              Note: You can "backup" as far as you like until
  334.                              the very beginning of the program.
  335.  
  336.      4.3  Maillist/Donation Assistance
  337.  
  338.           The first  screen  you see  is a  title,  information, and copyright
  339.           screen   with   a   "Press   Enter   to   continue   or  space   for
  340.           Maillist/Donation assistance"  prompt.  Normally, you will press the
  341.           Enter key  to start CROSSREF.  If you press the space bar, a program
  342.           will run  which will help you print a letter that you can send to us
  343.           to be sure  you are placed on our  maillist - particularly important
  344.           if you  did  not  receive  your  copy directly  from  us.  Amazingly
  345.           enough, the letter will even assist you in making a contribution but
  346.           that is not required (nice though).  
  347.  
  348.           Note: The  assistance  program  -  CRMAIL  -  is  contained  on  the
  349.           distribution disk  and its  copies but should not be  copied to your
  350.           DOS development  disk as  it is large, not required,  and a waste of
  351.           disk space.   CRMAIL is  chained from CROSSREF as it  resides on the
  352.           distribution disk  or may be executed directly from the distribution
  353.           disk by typing CRMAIL.  
  354.  
  355.      4.4  Program Entry
  356.  
  357.           The next question  you will be asked is to specify the Drive address
  358.           that contains  the program(s) to be referenced.  This is followed by
  359.           the Program  Entry screen.  Up to 25 programs may be specified to be
  360.  
  361.      CROSSREF                          - 4 -        Computerenergy Corporation
  362.                                                           CHAPTER 4: OPERATION
  363.  
  364.  
  365.           listed  in  sequence  at  one  time.   NOTE:  Each  program must  be
  366.           previously saved in  ASCII format using the ",A"  option of the Save
  367.           command in Basic.  Example: 
  368.  
  369.                          SAVE "B:progname.S",A
  370.  
  371.           We use the  .S extension for "Source" to differentiate between Basic
  372.           encoded  programs  and  those saved  in ASCII.   This  approach also
  373.           provides  2 copies  of each  program as it is developed  - a sort of
  374.           automatic backup.  Any program extension may be used.  
  375.  
  376.           If a  program  is read  by CROSSREF  that  has accidentally not been
  377.           saved in ASCII,  CROSSREF will display an ERR=62  message and return
  378.           to DOS.  
  379.  
  380.           For each  program to  be  listed,  CROSSREF  asks  for 3  pieces  of
  381.           information -  program name, beginning line number to start listing,
  382.           ending line number to end listing.  Each program name may be entered
  383.           without an  extension and  CROSSREF will append the default  Program
  384.           Name Extension  from the  options file (originally = ".S").   If the
  385.           program  is entered  with an  extension,  then the entered extension
  386.           will be used.  
  387.  
  388.           Each line number field  is pre-loaded with a default  value from the
  389.           options file  which may  be changed most easily by  pressing the ESC
  390.           key and keying a new number or backspacing and re-keying the number.
  391.           The default  value  is  selected  by  pressing the  Enter  key.  The
  392.           beginning and  ending lines  specified will limit the lines  checked
  393.           for references but  will still list all references  found within the
  394.           range even if they refer to lines beyond the range.  
  395.  
  396.      4.5  Statistics and Limitations
  397.  
  398.           After each   program's   references   have  been   listed,  a  short
  399.           statistical summary  is printed.  The summary includes the number of
  400.           lines  read/processed,  symbols  referenced,  references,  beginning
  401.           line, and  ending line.   Both variable names and line  numbers that
  402.           are referenced are defined as symbols.  
  403.  
  404.      4.5.1  Limitations
  405.  
  406.           The critical number from  CROSSREF's point of view is  the number of
  407.           symbols.   CROSSREF's current  architecture will handle 500 symbols.
  408.           If a  program contains more symbols than that, we recommend that the
  409.           reference be done in 2 or more parts.  
  410.  
  411.           If you are using  a 64K system, the maximum  number of references is
  412.           around  1000.  If  you have  a 96K or larger system,  the maximum is
  413.           much larger.  
  414.  
  415.           It should also  be mentioned that CROSSREF will only print the first
  416.           12 characters of  a variable name.  Each variable  name's references
  417.           are kept  correctly by their full name though not fully reflected on
  418.           the table.  
  419.  
  420.  
  421.      CROSSREF                          - 5 -        Computerenergy Corporation
  422.                                                           CHAPTER 4: OPERATION
  423.  
  424.  
  425.      4.6  Programming Tip
  426.  
  427.           CROSSREF can  be used  to help  compact  programs by locating unused
  428.           variables that  may no  longer be required for a  program.  Look for
  429.           any  variable  names  that are  referenced only  once  - they may be
  430.           candidates for deletion.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.      CROSSREF                          - 6 -        Computerenergy Corporation
  482.                                       CHAPTER 5
  483.  
  484.                                    OPTION DEFAULTS
  485.  
  486.           The CROSSREF  Options file  - CROSSOPT  -  contains three data items
  487.           that  are  used by  CROSSREF to  preload entries for you.  They  are
  488.           referred to as default options or defaults.  
  489.  
  490.      5.1  Program Name Extension
  491.  
  492.           The Program Name Extension option is used by CROSSREF to concatenate
  493.           to any program name that is entered without an extension.  We use .S
  494.           for "Source" to differentiate from Basic encoded programs (.BAS) but
  495.           any extension is acceptable.  
  496.  
  497.           If a  program  name  is entered  with an  extension,  this option is
  498.           ignored.  
  499.  
  500.      5.2  Beginning Program Line Number
  501.  
  502.           The Beginning  Program Line  Number default establishes a value that
  503.           will be  preloaded into the Beginning Line Number prompt request for
  504.           each program  to be  referenced.  The value may be  changed at entry
  505.           time if desired.  
  506.  
  507.           We tend to place  a significant number of routines  (the MONITOR) at
  508.           lines  10 -  9999 and  therefore do not wish to  list these routines
  509.           over and  over.  The  beginning value we use is  10000 but any valid
  510.           line number is acceptable.  
  511.  
  512.      5.3  Ending Program Line Number
  513.  
  514.           The Ending Program Line Number default establishes a value that will
  515.           be  preloaded into  the Ending  Line Number prompt request for  each
  516.           program to be referenced.  The value may be changed at entry time if
  517.           desired.  
  518.  
  519.           The value we  use is  65529, which is the highest  valid line number
  520.           for a  Basic  program  and  therefore  will list  to  the end of the
  521.           program.  Any valid line number is acceptable.  
  522.  
  523.      5.4  Changing Default Options
  524.  
  525.           The Option file  - CROSSOPT  - is a sequential file  that contains a
  526.           single record with  3 fields.  The record, as  distributed, contains
  527.           the 3  default values in sequence: Program Name Extension, Beginning
  528.           Program Line Number, Ending Program Line Number separated by commas.
  529.           The record looks like: .S,10000,65529 
  530.  
  531.           The file may be  accessed and modified with EDLIN  or any other text
  532.           editor   or  word   processor  that  works  with  PC-DOS  compatible
  533.           sequential ASCII files.  
  534.  
  535.           If you are using EDLIN, the easiest way to change the defaults is as
  536.           follows: 
  537.  
  538.                1. Assuming that the CROSSOPT file is on the default drive, and
  539.                while in DOS, enter "EDLIN CROSSOPT" (without quotes).  
  540.  
  541.      CROSSREF                          - 7 -        Computerenergy Corporation
  542.                                                     CHAPTER 5: OPTION DEFAULTS
  543.  
  544.  
  545.                2. When EDLIN  prints "End of input file", key a 1.  EDLIN will
  546.                respond with a "1*".  
  547.  
  548.                3. Rekey the entire  line with the defaults changed  to the way
  549.                you want them, separated by commas, and press Enter.  
  550.  
  551.                4. After EDLIN displays "2*", press CTRL-BREAK.  
  552.  
  553.                5. After EDLIN displays the "*", key "E" (w/o quotes) and press
  554.                Enter.  The new file will be saved.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.      CROSSREF                          - 8 -        Computerenergy Corporation
  602.                                       CHAPTER 6
  603.  
  604.                                   OTHER INFORMATION
  605.  
  606.      6.1  Distribution Disk Contents
  607.  
  608.  
  609.                File Name       Description
  610.                ------------    --------------------------------------
  611.  
  612.                CROSSREF.EXE    Compiled CROSSREF
  613.                CROSSREF.DOC    Documentation
  614.                CROSSWDS.DAT    Basic Syntax File
  615.                CROSSOPT        Cross Reference Options File
  616.                CRMAIL.EXE      Maillist/Donation Assistance
  617.                CRCOPY.BAT      Copies Distribution Disk - both CROSSREF and
  618.                                    MONITOR
  619.  
  620.  
  621.      6.2  System Requirements
  622.  
  623.           CROSSREF requires an IBM  PC with 64K, DOS 1.1,  and at least 1 disk
  624.           drive (2 disks highly recommended for development machines).  
  625.  
  626.  
  627.      6.3  Disclaimer
  628.  
  629.           All Computerenergy  computer programs  are distributed on an "as is"
  630.           basis without warranty.  
  631.  
  632.           Computerenergy Corporation  and/or any  of its program authors shall
  633.           have no  liability or responsibility to customer or any other person
  634.           or entity  with respect  to any liability, loss or  damage caused or
  635.           alleged to  be caused directly or indirectly by programs distributed
  636.           in  any  manner  by  Computerenergy  Corporation, including  but not
  637.           limited  to  any  interruption  of  service,  loss  of  business  or
  638.           anticipatory profits or consequential damages resulting from the use
  639.           or operation of such computer programs.  
  640.  
  641.           Note: Good data processing procedure dictates that the user test the
  642.           program,  run and  test sample  sets of data, and run  the system in
  643.           parallel  with  the system  previously in  use for a period of  time
  644.           adequate to insure that results of operation of the computer program
  645.           are satisfactory.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.      CROSSREF                          - 9 -        Computerenergy Corporation
  662.                                       CHAPTER 7
  663.  
  664.                        SUGGESTIONS, FEEDBACK, AND BUG REPORTS
  665.  
  666.           If you  can spare  the time,  we would appreciate your feedback  and
  667.           suggestions to help us to improve CROSSREF.  As an added inducement,
  668.           we will  also send  a free CROSSREF (corrected) to  the first person
  669.           reporting  each  bug.   Immediate  family members  of Computerenergy
  670.           employees are NOT  eligible.  If possible, each bug  reported should
  671.           include a short-as-possible printout of the reference situation with
  672.           explanatory  notes.   Our unprejudiced  judging panel will make "Bug
  673.           Awards" when the  spirit moves them and, of  course, their decisions
  674.           are final.  
  675.  
  676.           We are also  aware of  some esthetic errors when operating  with the
  677.           color  video  interface.  Those  still remaining should be corrected
  678.           soon, but we'd still like to hear about any you find.  
  679.  
  680.           Please address correspondence to the address on the title page.  (If
  681.           you've lost  your title page, just send us a note and we'll send you
  682.           a new one.) 
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.      CROSSREF                          - 10 -       Computerenergy Corporation
  722.